Inside Macintosh: QuickTime Components
Sequence grabber components use channel components to obtain digitized data from external media. Your channel is assigned to a sequence grabber component when the application calls the sequence grabber component's SGNewChannel function, described in the chapter "Sequence Grabber Components" in this book. The sequence grabber component must configure your channel before a preview or record operation. Your channel component must provide a number of functions that allow the sequence grabber to configure the characteristics of your channel. Several of these functions work on any channel component. This section discusses these general channel configuration functions.
In addition, channel components provide functions that are specific to the channel type. The sequence grabber component supplied by Apple uses two types of channel components: video channel components and sound channel components. See "Configuration Functions for Video Channel Components," which begins on Configuration Functions for Video Channel Components , for information about the configuration functions that work only with video channels. See "Configuration Functions for Sound Channel Components," which begins on Configuration Functions for Sound Channel Components , for information about the configuration functions that work only with sound channels.
The SGSetChannelUsage function specifies how your channel is to be used. The sequence grabber component can restrict a channel to use during record or preview operations. In addition, this function allows the sequence grabber component to specify whether your channel plays during a record operation. The SGGetChannelUsage function allows the sequence grabber component to determine a channel's usage.
The SGGetChannelInfo function allows the sequence grabber component to determine some of the characteristics of your channel. For example, this function returns information indicating whether your channel has a visual or an audio representation.
The SGSetChannelPlayFlags function lets the sequence grabber component influence the speed and quality with which your channel plays captured data. The SGGetChannelPlayFlags function allows the sequence grabber component to determine these flag settings.
The SGSetChannelMaxFrames function establishes a limit on the number of frames that your channel component will capture from a channel.
The SGGetChannelMaxFrames function enables the sequence grabber component to determine that limit.
The SGSetChannelRefCon function allows the sequence grabber component to set the value of a reference constant that your component passes to its callback functions (see "Using Callback Functions for Video Channel Components," which begins on Using Callback Functions for Video Channel Components , for information about the callback functions that are supported by video channels).
The SGGetDataRate function allows the sequence grabber component to determine how many bytes of captured data your channel is collecting each second.
The SGGetChannelSampleDescription function allows the sequence grabber to retrieve your channel's sample description. The SGGetChannelTimeScale function allows it to obtain your channel's time scale.
The sequence grabber can modify or retrieve your channel's clipping region by calling the SGSetChannelClip or SGGetChannelClip function, respectively. The sequence grabber can work with your channel's transformation matrix by calling the SGSetChannelMatrix and SGGetChannelMatrix functions.
The SGSetChannelUsage function specifies how your channel is to be used by the sequence grabber component.
pascal ComponentResult SGSetChannelUsage (SGChannel c,
long usage);
The SGGetChannelUsage function allows the sequence grabber to determine how your channel is to be used.
pascal ComponentResult SGGetChannelUsage (SGChannel c,
long *usage);
The SGGetChannelInfo function allows the sequence grabber to determine how a channel's data is represented to the user--as visual or audio data, or both.
pascal ComponentResult SGGetChannelInfo (SGChannel c,
long *channelInfo);
The SGSetChannelPlayFlags function allows the sequence grabber component to influence the speed and quality with which your channel component displays data from its source.
pascal ComponentResult SGSetChannelPlayFlags (SGChannel c,
long playFlags);
The SGGetChannelPlayFlags function allows the sequence grabber component to retrieve the playback control flags that it set with the SGSetChannelPlayFlags function, which is described in the previous section.
pascal ComponentResult SGGetChannelPlayFlags (SGChannel c,
long *playFlags);
The SGSetChannelMaxFrames function allows the sequence grabber to limit the number of frames that your channel component will capture during a record operation.
pascal ComponentResult SGSetChannelMaxFrames (SGChannel c,
long frameCount);
The SGSetChannelMaxFrames function works only with channels that have data that is organized into frames, such as video data from a video disc.
You report whether your channel's data is organized into frames in your response to the SGGetChannelInfo function, which is described on SGGetChannelInfo .
The SGGetChannelMaxFrames function allows the sequence grabber component to determine the number of frames left to be captured from your channel.
pascal ComponentResult SGGetChannelMaxFrames (SGChannel c,
long *frameCount);
The SGSetChannelRefCon function allows the sequence grabber component to set the value of a reference constant that your component passes to its callback functions.
pascal ComponentResult SGSetChannelRefCon (SGChannel c,
long refCon);
See "Using Callback Functions for Video Channel Components," which begins on Using Utility Functions for Video Channel Component Callback Functions , for a description of the callback functions that are supported by video channel components.
The sequence grabber component calls your component's SGGetDataRate function in order to determine how much recording time is left. The sequence grabber calls your component when an application calls the sequence grabber component's SGGetTimeRemaining function (see the chapter "Sequence Grabber Components" in this book for details) .
pascal ComponentResult SGGetDataRate (SGChannel c,
long *bytesPerSecond);
Your component should calculate and return a value indicating the number of bytes of data your component is recording per second. The sequence grabber component uses this information, along with similar information gathered from other channels being used in the recording operation, to determine how many seconds of data may be recorded given the amount of space remaining.
The SGGetChannelSampleDescription function allows the sequence grabber to retrieve your channel's sample description.
pascal ComponentResult SGGetChannelSampleDescription
(SGChannel c, Handle sampleDesc);
The SGGetChannelSampleDescription function allows the sequence grabber to retrieve your channel's current sample description. The sequence grabber may call this function only when your channel is prepared to record or is actually recording.
Your channel returns a sample description that is appropriate to the type of data being captured. For video channels, your channel component returns an Image Compression Manager image description structure; for sound channels, you return a sound description structure, as defined by the Movie Toolbox.
The SGGetChannelTimeScale function allows the sequence grabber to retrieve your channel's time scale.
pascal ComponentResult SGGetChannelTimeScale (SGChannel c,
TimeScale *scale);
The time scale you return typically corresponds to the time scale of the media that has been created by your channel. Applications may use this time scale in their data functions (see the chapter "Sequence Grabber Components" in this book for more information about application-defined data functions).
The SGSetChannelClip function allows the sequence grabber to set your channel's clipping region.
pascal ComponentResult SGSetChannelClip (SGChannel c,
RgnHandle theClip);
The SGGetChannelClip function allows the sequence grabber to retrieve your channel's clipping region.
pascal ComponentResult SGGetChannelClip (SGChannel c,
RgnHandle *theClip);
The SGSetChannelMatrix function allows the sequence grabber to set your channel's display transformation matrix.
pascal ComponentResult SGSetChannelMatrix (SGChannel c,
const MatrixRecord *m);
The SGSetChannelMatrix function allows the sequence grabber to specify a display transformation matrix for a video channel. Your channel uses this matrix to transform its video image into the destination window. If your channel cannot accommodate the matrix, return an appropriate result code. Note that the sequence grabber may not call this function when you are recording.
Other channel component functions may affect this matrix. The SGSetChannelBounds function sets the matrix values so that the matrix maps the channel's output to the channel's boundary rectangle (described on SGSetChannelBounds ). The SGSetVideoRect function modifies the matrix so that the specified video rectangle appears in the existing destination rectangle (see SGSetVideoRect for more information about the SGSetVideoRect function).
The SGGetChannelMatrix function allows the sequence grabber to retrieve your channel's display transformation matrix.
pascal ComponentResult SGGetChannelMatrix (SGChannel c,
MatrixRecord *m);